home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / LIBRARY / PBLIB1 / DOC / SPECS.TXT < prev    next >
Text File  |  1994-05-01  |  4KB  |  94 lines
  1.  
  2.               Pascal Public Domain Library Specifications
  3.  
  4. This is simply my current thoughts and something to start arguing from.
  5. Howard Richoux
  6.  
  7.  
  8. 1. Licensing - Free to ALL, commercial and personal use.  The only
  9.       restriction is to require code source credit as appropriate.
  10.       Copyright retained by who?
  11.  
  12. 2. Target users: Borland Pascal version 7, real mode.  Should wind up
  13.       TP6 compatible with little effort.  Will need help to assure
  14.       protected mode compatibility.   How about BPW?
  15.  
  16. 3. Suggested structure: Until a better model is presented, I suggest the
  17.       following:
  18.  
  19.       level 1 - one or more large TPUs containing general purpose, minimum
  20.         global routines.  Rely on linker to trim out un-referenced code and
  21.         data.  Use SYSTEM unit only, CRT adds a big chunk.  "Hello world"
  22.         program should be virtually unaffected by a uses of a level 1 unit.
  23.         Use minimum of calls of other level 1 routines.
  24.  
  25.       level 2 - routines and objects referencing level 1 support.  Try for
  26.         minimum cross referencing of level 2 structures and code.
  27.  
  28.       level 3 - a single call might bring in 10s of K of code and or data
  29.         from lower levels.
  30.  
  31.       level 4 - references commercial or otherwise restricted code.
  32.         Requirements need to be spelled out.
  33.  
  34. 4. Criteria for inclusion:
  35.     - Nearly anything which is used more than once belongs in a library.
  36.     - Resource use should be commensurate with benefits.  Large functions
  37.         need to be broken down so that the compiler can trim out unused
  38.         code and data.
  39.  
  40. 5. Coding standards.  A lot of this is personal taste and habits, but
  41.       some standardization is necessary to make it easy to code from
  42.       memory rather than have to constantly refer to documentation.  I
  43.       keep finding inconsistancies in my own naming schemes, but I have
  44.       found it best to fix them when detected rather than be faced with
  45.       a much larger job down the road.
  46.  
  47.      External standards - I expect we should prefix every procedure and
  48.        function name with something like Pb  (for Public) to make it
  49.        obvious where to look.  I like having the last portion of the
  50.        name indicate Function return type (like PbBooleanStr returning
  51.        results as a string).
  52.  
  53.      Internal standards - Much tougher.  I have a personal bias against
  54.        code that looks like a snake:
  55.           xxxxxx
  56.            xxxx
  57.            xxx
  58.             xxxx
  59.            xxxx
  60.           xxx
  61.  
  62.        and I like:
  63.           If xxxxx then
  64.                begin
  65.                yyyy
  66.                end;
  67.  
  68.        I suspect that others will disagree violently.  This is a discussion
  69.        point.
  70.  
  71. 6. Utility programs
  72.  
  73. One of the keys to standards is the tools provided to support them.  It would
  74. not be unreasonable to provide a program lister that could convert back and
  75. forth between styles.  I have most of a "ChangeAll" program so I can change
  76. names easily.  The USES utility helps resolve unit problems.  TMAP has been
  77. very useful to me in turning TP map files into something that makes sense.  the
  78. trouble is that about 5% of the information is either missing from the map
  79. file, or I just am interpreting it wrong.   UNITSCAN builds a .dbf file of
  80. function and procedure names and a specific type of comment, from the interface
  81. section of a unit source file.  It has limitations, but can be useful.  By
  82. incorporating {section xxxx } type comments in the source files, I can use
  83. TPRINT to extract specific sections (such as interface info) into documents
  84. directly from the source code.  SORTSECT can re-arrange the segments into
  85. alphabetical order.
  86.  
  87. All of these utilities are 95% or so of what they really ought to be.  They
  88. work, but have some minor unreasonable limitations.  Documentation is minimal -
  89. I wrote them so I should know how they work (ha ha).  With a little work,
  90. they could form the basis of a workable development environment.
  91.  
  92. One of my other little utilities is TP, my substitute for the IDE.  This is
  93. not ready for prime time, but it lets me work the way I want to.  Someone
  94. else can re-program it totally differently if they choose.